xSTRa System Calls.

xSTRa includes all the standard STREAMS utility routines, a number of common UNIX kernel functions such as timeout, and additional routines to support special features such as resource management. The xSTRa system calls are grouped by function below:

Message Management

allocb (size, priority)

Allocb allocates and initializes a message block and data block and returns a pointer to the message block. The data block is allocated from the smallest class large enough to hold size bytes.

freeb (mp)

Freeb releases a message block to the free pool and decrements the reference count of its data block. If the reference count becomes zero, it also releases the data block to the free pool for its class.

freemsg (mp)

Given a pointer to the first block of a message, freemsg uses freeb to release all its message blocks and all data blocks for which the reference counts become zero.

testb (size, priority)

Testb returns the number of available data blocks of the specified size and at the specified allocation priority.

bufcall (size, pri, func, arg)

Bufcall is used to request a callback when a data block of the specified size becomes available at the specified allocation priority pri. The callback routine func will be called with the input parameter argsize is released and the number of blocks in the free pool for that class is above the low-water mark for the specified priority.

copyb (mp)

Given a pointer to an existing message block, copyb allocates a new message and data block (using allocb), and copies the information from the existing blocks to the new blocks.

copymsg (mp)

Copymsg copies an entire message, using copyb to copy each block. A pointer to the first block of the existing message is supplied on input.

dupb (mp)

Dupb duplicates a message block by allocating a new message block and initializing it to point to the data block of an existing message block. The reference count of the data block is incremented.

dupmsg (mp)

Dupmsg uses dupb to duplicate each message block within a message. Each new message block points to the same data block as the corresponding existing message block, and the reference count of each data block is incremented. The new message blocks are linked to form a new message that shares the data blocks of the existing message.

rmvb (mp, mbp)

Rmvb unlinks a message block (mbp) from a messge (mp). The block to be unlinked may be at any location within the message. If other blocks precede and follow the one to be removed, those blocks are linked together so that the messge remains intact.

unlinkb (mp)

Given a pointer to the first block of a message, unlinkb unlinks it from the remaining blocks of the message (if any).

adjmsg (mp, count)

Given a pointer to the first block of a message and a count, adjmsg removes the specified number of bytes from the beginning or end of a message (depending on whether count is a positive or negative value).

pullupmsg (mp, count)

Given a pointer to the first block of a message and a count, pullupmsg copies the specified number of bytes from the data blocks of the message into a single large data block. It links the new data block to the first message block, releases all emptied data blocks and their associated message blocks (except the first), and links the remainder of the message (if any) to the first message block.

linkb (mp1, mp2)

Given a pointer to the first block of each of two messgage, linkb links the last block of the first message to the first block of the second, forming a single message.

msgdsize (mp)

Given a pointer to message block, msgdsize calculates the total number of bytes of data in all data blocks of the message that have type M_DATA. (Data blocks of other types are skipped and their contents are not counted in the total.)

datamsg (type)

Datamsg is a macro that compares type with the three data message types, M_DATA, M_PROTO and M_PCPROTO.

Queue Management

getq (q)

Getq removes a message from the head of the specified queue.

putq (q, mp)

Putq adds a message to a queue and schedules it for execution. A regular-priority message is always added to the tail of the queue. A high-priority message is added to the queue following any other high-priority messages already on the queue, but preceding any regular-priority messages.

putbq (q, mp)

Putbq puts a message back on a queue. A high-priority message is always added to the head of the queue. A regular-priority message is added to the queue following any high-priority messages, but preceding any other regular-priority messages.

canput (q)

Canput returns a value indicating whether or not the specified queue is full. A service procedure following the flow control rules generally calls canput to determine whether it should pass a message to the next module in the stream using putnext.

insq (q, emp, mp)

Insq adds a message (mp) to a queue at a position immediately preceding an existing message (emp) that is already on the queue. If the existing message pointer is NULL, the new message is added to the tail of the queue. The message is placed on the queue at the requested location regardless of its priority or the priority of other messages on the queue.

rmvq (q, mp)

Given a pointer to a queue and a pointer to the first block of a message on the queue, rmvq removes the message from the queue.

backq (q)

Given a pointer to a queue, backq finds the previous queue in the stream. That is, it returns a pointer to the queue upstream from a write queue or downstream from a read queue.

flushq (q, flag)

Depending on the value of flag, flushq removes and releases all messages on the specified queue, or only messages of type M_DATA, M_PROTO, and M_PCPROTO.

qsize (q)

Qsize returns the number of messages on the specified queue.

RD (q)

RD is a macro. Given a pointer to a write queue, it returns a pointer to the read queue.

WR (q)

WR is a macro. Given a pointer to a read queue, it returns a pointer to the write queue.

OTHERQ (q)

OTHERQ is a macro that locates the specified queue's partner. That is, given a pointer to a write queue, it returns a pointer to the read queue; given a pointer to a read queue, it returns a pointer to the write queue.

Scheduling and Data Processing

putnext (q, mp)

The macro putnext calls the put procedure of the next queue in the stream. That is, if a write queue is specified, putnext calls the write put procedure of the next module downstream. If a read queue is specified, it calls the read put procedure of the next module upstream.

qreply (q, mp)

Qreply calls the put procedure of the next queue in the stream, but in the opposite direction from the specified queue. That is, if a write queue is specified, qreply calls the read put procedure of the next module upstream. If a read queue is specified, it calls the write put procedure of the next module downstream.

qenable (q)

Qenable schedules the specified queue for execution.

putctl (q, type)

Putctl creates a control message and calls the put procedure of the specified queue. To create the message, putctl calls allocb to allocate a message and data block, and sets the message type as specified on input.

putctl1 (q, type, byte)

Putctl1 creates a control message and calls the put procedure of the specified queue. To create the message, putctl calls allocb to allocate a message and data block, sets the message type as specified on input, and stores the specified byte in the data block.

noenable (q)

Noenable disables scheduling of a queue.

enableok (q)

Enableok re-enables scheduling of a queue.

canenable (q)

Canenable is a macro. It returns a value indicating whether the specified queue has been disabled using noenable.

sleep (param)

Sleep suspends execution of the currently running queue. The specified parameter is saved and the queue is added to the system's sleep list. The queue will not be dispatched again to complete execution of its service procedure until wakeup is called with the same input parameter.

wakeup (param)

Wakeup searches the system's sleep list, removing and scheduling any queues with the specified parameter saved in their queue structures. When a queue is dispatched after being awakened, it continues execution at the return from its call to sleep.

runlock ()

Runlock sets a flag that prevents the system from preempting the currently executing queue, even if its time slice should expire.

rununlock ()

Rununlock clears the system's preemption lock flag.

Memory Management

malloc (size)

Malloc allocates a block of the specified size from the system's free memory region. Memory blocks of any size can be allocated dynamically.

free (block)

Free releases a block of memory that was previously allocated with malloc. The input parameter is a pointer to the start of the block.

realloc (block, size)

Given the address of a block of memory that was previously allocated with malloc, realloc extends or contracts the block to the specified size.

Miscellaneous Support Functions

addisr (devid, isr)

Addisr installs an interrupt service routine isr for the interrupt source identified by devid.

freeisr (devid)

Freeisr frees the specified interrupt source for use by another module.

timeout (func, arg, ticks)

Timeout starts a timer for the specified number of ticks. When the timer expires, the system's timer module calls the routine func with the input parameter arg. Each tick is equivalent to 10 milliseconds.

untimeout (tval)

Given a unique timer ID (supplied on return from timeout), untimeout cancels the timer.

spl

The macros spl0 through spl7 set the processor's interrupt mask to the corresponding level. Splhi and splstr are synonymous with spl7. The routine splx sets the interrupt mask to the level specified on input. The routine splr sets the mask to the level specified on input, but only if that level is higher than the current interrupt mask level.

printf (format [,arg...])

Printf displays a message on the console. The first parameter is a pointer to a format string. An additional argument must be passed to printf for each conversion specification within the format string.

mktoken (name)

Mktoken creates a resource token with the specified name. Resource tokens can be used to coordinate the assignment of resources, such as serial links, among multiple streams.

gettoken (name, sleepflag)

Gettoken allocates the resource token specified by name. If the resource token is not available, the action taken depends on the value of sleepflag. Either an error is returned, or the request does not complete until the token is available and has been allocated to the caller.

reltoken (name)

Reltoken releases the resource token specified by name.

soutb (address, value)

Soutb writes a byte (value) at the specified address. It is intended for writes to hardware registers that cannot be accessed from user state.

Ordering Information: For more information or to place an order, please contact us at (619) 627-1700 or email us at sales@uconx.com . For technical questions about our products, please email us at tech@uconx.com .